import { PackageManagerTabs } from '@theme';

# Customizing page

Rspress provides several ways for you to customize the content of your pages, including:

- Adding custom global components.
- Adding custom global styles.
- Customizing page layout structure.

## Custom global components

In some scenarios, you may need to add some custom global components to the page. Rspress provides a config item `globalUIComponents` to achieve this function.

### How to use

Add the following config in `rspress.config.ts`:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});
```

Each item of `globalUIComponents` can be a string, representing the file path of the component; or it can be an array, the first item is the file path of the component, and the second item is the props object of the component, such as:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  globalUIComponents: [
    [
      path.join(__dirname, 'components', 'MyComponent.tsx'),
      {
        foo: 'bar',
      },
    ],
  ],
});
```

import GlobalUIComponents from '@en/fragments/global-ui-components';

<GlobalUIComponents />

## Custom styles

In some scenarios, you may need to add some global styles on top of the theme UI. Rspress provides a configuration item `globalStyles` to achieve this function.

### How to use

Add the following configuration in `rspress.config.ts`:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  globalStyles: path.join(__dirname, 'styles/index.css'),
});
```

Then you can add the following code:

```css title="styles/index.css"
:root {
  --rp-c-brand: #f00;
}
```

In this way, Rspress will automatically collect all global styles and merge them into the final style file.

Here are some commonly used global styles:

```css title="styles/index.css"
:root {
  /* Modify theme color */
  --rp-c-brand: #f00;
  --rp-c-brand-dark: #ffa500;
  --rp-c-brand-darker: #c26c1d;
  --rp-c-brand-light: #f2a65a;
  --rp-c-brand-lighter: #f2a65a;
  /* Modify the width of the left sidebar */
  --rp-sidebar-width: 280px;
  /* Modify the width of the right outline column */
  --rp-outline-width: 256px;
  /* Modify the background of the code block title */
  --rp-code-title-bg: rgba(250, 192, 61, 0.15);
  /* Modify the background of the code block content */
  --rp-code-block-bg: rgba(214, 188, 70, 0.05);
}
```

> If you want to know more about the internal global styles, you can check [vars.css](https://github.com/web-infra-dev/rspress/blob/main/packages/theme-default/src/styles/vars.css)

### Tailwind CSS

In order to get Tailwind CSS working with Rspress, you can use the following steps:

1. Install Tailwind CSS:

<PackageManagerTabs command="install tailwindcss -D" />

2. Create a `postcss.config.js` file containing `tailwindcss` plugin:

```js title="postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
  },
};
```

3. Create a `tailwind.config.js` file and make sure all the content files are included via `content`:

```js title="tailwind.config.js"
module.exports = {
  content: ['./src/**/*.tsx', './docs/**/*.mdx'],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

4. Include the Tailwind directives in your CSS styles file from [Custom Styles](#custom-styles):

```css title=styles/index.css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
```

> For most up to date configuration, please refer to the official [Tailwind CSS documentation](https://tailwindcss.com/docs/installation/using-postcss).

## Custom layout structure

### Using pageType

Rspress provides a pageType configuration for you to customize the layout structure of the page.

Rspress's convention-based routing supports two types of routes, one is document routing, that is, pages written with md(x) files, and the other is component routing, that is, pages written with `.jsx/.tsx` files.

For the former, you can add the `pageType` field in the frontmatter to specify the layout structure of the page, such as:

```mdx title="foo.mdx"
---
pageType: custom
---
```

For the latter, you can add the following export to specify `pageType`:

```tsx title="foo.tsx"
export const frontmatter = {
  // Declare layout type
  pageType: 'custom',
};
```

pageType can be configured as the following values:

import PageType from '@en/fragments/page-type.mdx';

<PageType />

### Using fine-grained switches

In addition to the `pageType` page layout level configuration, Rspress also provides more fine-grained switches. You can configure other fields in the frontmatter. These fields and their meanings are as follows:

- `navbar`: Whether to display the top navigation bar. When you want to hide the top navigation bar, you can set it to `false`.
- `sidebar`: Whether to display the sidebar. When you want to hide the sidebar, you can set it to `false`.
- `outline`: Whether to display the outline column. When you want to hide the outline column, you can set it to `false`.
- `footer`: Whether to display the footer. When you want to hide the footer, you can set it to `false`.

Example:

```mdx title="foo.mdx"
---
navbar: false
sidebar: false
outline: false
footer: false
globalUIComponents: false
---
```

### Using URL parameters as switches

In addition, you can use URL parameters to control the layout structure of the page at runtime, such as:

```bash
# Hide the navigation bar and outline in the right column
http://YOUR_DOMAIN/foo?navbar=0&outline=0
```

With URL parameters, you can quickly adjust the layout structure of the page without modifying the source code. These parameters specifically include:

- `navbar`: Whether to display the navigation bar. When you want to hide the top navigation bar, you can set it to `0`.
- `sidebar`: Whether to display the sidebar. When you want to hide the sidebar, you can set it to `0`.
- `outline`: Whether to display the outline column. When you want to hide the outline column, you can set it to `0`.
- `footer`: Whether to display the footer. When you want to hide the footer, you can set it to `0`.
- `globalUIComponents`: Whether to display the global components. When you want to hide the global components, you can set it to `0`.

## Custom tags

### Customizing head tag

In `rspress.config.ts`, you can custom HTML's metadata (aka head tag) for all pages. We explain it with more details in [basic config - head](/api/config/config-basic#head) within the api section.

### Generate metadata tags

Within frontmatter, you can also customize your page's metadata tag for SEO optimization.

For example, if you want to add `<meta name="description" content="This is description">` in your `<head>` tag, you can use frontmatter like so:

```md title="example.mdx"
---
head:
  - - meta
    - name: title
      content: This is title
  - - meta
    - name: description
      content: This is description
---
```

### Open Graph tags

[Open Graph](https://ogp.me/) is a web metadata protocol used to control how pages are displayed when shared on social media platforms.

Rspress automatically injects the following Open Graph meta tags for each page:

- `og:type`: Fixed value of `website`
- `og:title`: Automatically uses the current page's title

If you need to customize more Open Graph tags (such as `og:image`, `og:title`, etc.), please refer to [frontmatter configuration](/api/config/config-frontmatter#head).
